package com.wenx.v3system.modular.cloud.service;

import com.baomidou.mybatisplus.extension.service.IService;
import com.wenx.v3system.modular.cloud.domain.dto.SysPermissionDto;
import com.wenx.v3system.modular.cloud.domain.po.SysPermission;
import com.wenx.v3system.modular.cloud.domain.po.SysPermissionCondition;

import java.util.List;
import java.util.Map;
import java.util.Set;

/**
 * 权限管理核心业务服务接口
 * 专注于权限条件验证、权限继承、权限树构建等核心业务逻辑
 * CRUD操作请使用 SysPermissionRestService
 * 
 * @author wenx
 * @since 1.0.0
 */
public interface SysPermissionService extends IService<SysPermission> {

    // ============= 权限条件验证相关 =============

    /**
     * 验证权限条件
     * 根据权限条件配置验证用户是否满足权限要求
     * 
     * @param userId 用户ID
     * @param permissionCode 权限代码
     * @param context 上下文参数（如资源ID、部门ID等）
     * @return 是否满足权限条件
     */
    boolean validatePermissionConditions(Long userId, String permissionCode, Map<String, Object> context);

    /**
     * 获取权限的所有条件配置
     * 
     * @param permissionCode 权限代码
     * @return 权限条件列表
     */
    List<SysPermissionCondition> getPermissionConditions(String permissionCode);

    /**
     * 评估权限表达式
     * 支持复杂的权限条件表达式计算
     * 
     * @param expression 权限表达式
     * @param context 上下文参数
     * @return 表达式计算结果
     */
    boolean evaluatePermissionExpression(String expression, Map<String, Object> context);

    // ============= 权限继承与层级关系 =============

    /**
     * 获取权限的所有父权限
     * 
     * @param permissionCode 权限代码
     * @return 父权限代码集合
     */
    Set<String> getParentPermissions(String permissionCode);

    /**
     * 获取权限的所有子权限
     * 
     * @param permissionCode 权限代码
     * @return 子权限代码集合
     */
    Set<String> getChildPermissions(String permissionCode);

    /**
     * 检查权限是否具有继承关系
     * 
     * @param parentCode 父权限代码
     * @param childCode 子权限代码
     * @return 是否存在继承关系
     */
    boolean hasInheritanceRelation(String parentCode, String childCode);

    // ============= 权限树构建与查询 =============

    /**
     * 构建用户可访问的权限树
     * 根据用户权限过滤并构建权限树
     * 
     * @param userId 用户ID
     * @param type 权限类型（可选）
     * @return 用户权限树
     */
    List<SysPermissionDto> buildUserPermissionTree(Long userId, String type);

    /**
     * 构建完整权限树（管理员视图）
     * 
     * @param type 权限类型
     * @param status 状态
     * @return 完整权限树
     */
    List<SysPermissionDto> buildFullPermissionTree(String type, String status);

    /**
     * 获取权限路径
     * 从根节点到指定权限的完整路径
     * 
     * @param permissionCode 权限代码
     * @return 权限路径列表
     */
    List<SysPermissionDto> getPermissionPath(String permissionCode);

    // ============= 权限作用域处理 =============

    /**
     * 检查权限作用域
     * 验证用户在指定作用域下是否拥有权限
     * 
     * @param userId 用户ID
     * @param permissionCode 权限代码
     * @param scope 作用域（department, team, owner等）
     * @param scopeId 作用域ID
     * @return 是否拥有权限
     */
    boolean checkPermissionScope(Long userId, String permissionCode, String scope, Long scopeId);

    /**
     * 获取用户在指定权限下的作用域范围
     * 
     * @param userId 用户ID
     * @param permissionCode 权限代码
     * @return 作用域ID集合
     */
    Set<Long> getUserPermissionScope(Long userId, String permissionCode);

    // ============= 权限缓存管理 =============

    /**
     * 刷新权限缓存
     * 
     * @param permissionCode 权限代码（可选，为空则刷新所有）
     */
    void refreshPermissionCache(String permissionCode);

    /**
     * 清除权限缓存
     */
    void clearPermissionCache();

    // ============= 权限统计与分析 =============

    /**
     * 统计权限使用情况
     * 
     * @param permissionCode 权限代码
     * @return 使用统计信息
     */
    Map<String, Object> getPermissionUsageStats(String permissionCode);

    /**
     * 获取孤立权限列表
     * 查找没有被任何角色使用的权限
     * 
     * @return 孤立权限列表
     */
    List<SysPermissionDto> getOrphanPermissions();
}